Extract Templates section of manual to its own document #10431
Conversation
and use it on templates.md manfilter.lua learns how to turn a link to another document in docs/ into a manual page cross-reference. This is paralleled by a pandoc-website filter change for handling such links. a lightly customized template for turning arbitrary docs into manual pages is provided, which exploits the standard `subtitle` metadata for the NAME section of the manual This first stab at this work does the brutal minimum amount of work while still being somewhat extensible. The new Makefile rule that applies the new man template hardcodes section 5. The mapping of document titles to manpage names and sections used by the lua filter is hardcoded at the top. Cleverer ideas could reduce repetition, at the cost of having to read yaml frontmatter out of all the docs to support cross-references, or relying on exotic GNU Make tricks, or similar.
Some unrelated changes picked up in pandoc.1 since that's usually a release task.
|
I'm still not sure about this one. Note that there are references in the manual to, e.g. Also, the entire "Variables" subsection seems more relevant to the average user of pandoc than the details of template syntax. After all, this is the part that tells you how to specify the font, font size, margins, and so on for your target format. With the proposed change, this would go in templates.md and readers of the pandoc manual might not even know to look there. |
|
Thanks for the notes and calling out the reference links I missed. I didn’t really do any developmental editing on the proposed |
|
Thinking about this a bit more: I don't think it makes sense to break out the whole Templates section. As noted above, the "Variables" part belongs with the main pandoc page, both because this gives crucial information about how to do things like set margins and font sizes, and because it describes variables that are set by or interpreted by the pandoc executable, not the syntax of templates. The introductory part about what templates are and how you use them also belongs with the main manual. The subsection |
This is by way of a proof-of-concept or initial attempt at the work discussed in #10351. This PR proposes initial handling of the cross-reference links to the erstwhile Templates section in
MANUAL.txtby just making them links totemplates.mdthat are cleaned up by lua filters for the manual page generation (here) and the website (in a related change over there, jgm/pandoc-website#65).None of this is quite perfect but it does function, with minimal churn in
MANUAL.txt. The system could be stress-tested further by adding man page generation for more of the existing extra docs but I haven't done so so far. The main thing bothering me about what I have here is that documents will have to be paired with the right manual section in multiple places.